Improve docs for shape and a la carte shaping functions #5172
Conversation
docs/language/functions/fill.md
Outdated
| The order of newly added fields relative to fields already present is | ||
| undefined. If maintaining relative order is important, consider applying the | ||
| [`order`](./order.md) or [`shape`](./shape) function. |
There was a problem hiding this comment.
I stuck with "undefined" since I don't know the code. If we think there's something more detailed we could say that's not too complicated I'd be happy to set more explicit expectations (e.g., if/when it can be expected to append the new fields).
docs/language/functions/fill.md
Outdated
| The order of newly added fields relative to fields already present is | ||
| undefined. If maintaining relative order is important, consider applying the | ||
| [`order`](./order.md) or [`shape`](./shape.md) function. |
There was a problem hiding this comment.
Fields are added in the order they appear in the input record.
There was a problem hiding this comment.
For reference, fill essentially happens here:
zed/runtime/sam/expr/shaper.go
Lines 274 to 275 in f497079
(That's inside a loop that, for fill, iterates over the fields of the input record.)
There was a problem hiding this comment.
After seeing @nwt's comments here we had a quick offline chat and agreed on some text to clarify where fill adds the fields rather than the "undefined" I had before. I've pushed a commit with that change.
When it comes to working with records, we've had some internal consensus that users will probably prefer
shapemost of the time whereas the "a la carte" functionscast,fill, andorderare probably going to see more limited use. Addressing the questions posed by the community user that opened #5168 made me realize this is not really called out in the docs, so I'm attempting to do that here, along with a couple other bits of polish I saw in the pages along the way.